The PCC RESTful Web Services are designed to run out-of-the-box on a single server. In the single-server mode, the PCC RESTful Web Services are listening on port 18681 by default and fulfilling requests entirely on the same server. There is no additional configuration to run in single-server mode. This mode is recommended if you have only one server hosting the PCC RESTful Web Services.

If your application requires more bandwidth or processing power than one server can handle, the PCC RESTful Web Services provide a mode that enables request load balancing and routing across multiple servers hosting the services. The following topic discusses the requirements and considerations for running the PCC RESTful Web Services in multi-server mode.

Multi-Server Mode

Before getting into the details of multi-server mode, it’s important understand two things about how the PCC services generate and serve content:

• The majority of requests the PCC service handles are centered around a document conversion from one format to another. These conversions consume processor time, so the PCC service attempts to conserve as much CPU resources as possible by caching content as its converted.
• Cached content is only stored locally on the server where it was created and it is directly tied to a specific viewing session. This means that requests for an existing viewing session must be handled by the PCC service on the server that originally created it, otherwise errors will occur.

The caching behavior mentioned above places some requirements on the PCC service running in multi-server mode. Luckily, the PCC service itself ensures most of these requirements are met.

How It Works

The multi-server mode of the PCC service works by creating a new entry point on each server hosting the PCC HTTP service. This new entry point becomes responsible for routing requests to the correct PCC server, as well as load balancing requests for new viewing sessions over all the PCC servers in the node.

Consider the diagram below which depicts an architecture that employs 3 servers hosting the PCC HTTP service within a node. Looking deeper, notice that each server is hosting two entry points:

The Server Entry Point (SEP) will be listening on port 18681 by default. This is the main PCC HTTP service entry point for the server. It is responsible for routing requests to the internal services running on the server. It is also the same entry point that handles requests from your application in single-server mode. However, in multi-server mode your application should not send requests directly to the SEP, but instead the requests should be made to the Cloud Entry Point.

The Cloud Entry Point (CEP) will be listening on port 18682 by default. In multi-server mode, the CEP is responsible for routing requests to the correct PCC server. If you are creating a new viewing session, the CEP will assign that session to a PCC server it chooses. If you are working with an existing viewing session, the CEP will ensure that the request is forwarded on to the server which that viewing session is associated with. Any CEP can route any request to the correct server. This allows you to use a simple load balancer in front of your PCC servers; simply have the load balancer send incoming requests to any CEP on any server and the CEPs will ensure that the requests are routed to the appropriate machine.

Configuration

After installation, the PCC HTTP service will be running in single-server mode. To enable multi-server mode:

1. Stop the Prizm Services.
2. Open the Watchdog configuration file in a text editor. The default path to this file is:

• Windows: C:\Prizm\PCCIS\Watchdog\watchdog.config
• Linux: /usr/share/prizm/pccis/Watchdog/watchdog.config

3. Set the server_mode value to multi, and make sure the sep_port and cep_port values exist and are assigned to valid port numbers:

    "server_mode": "multi",

    "sep_port": 18681,

    "cep_port": 18682,

4. Save and close the Watchdog configuration file.
5. Start the Prizm Services. 

If your application makes requests to the PCC service from another server, ports 18681 and 18682 (or other port values you choose) will need to be opened in the firewall for each server hosting the PCC service.

Start-Up

Once the PCC HTTP service has been configured and is running on each server, there is one more critical step you must perform before the Cloud Entry Points will able to handle requests successfully. In this step you will inform the Cloud Entry Point on each PCC server of the other available PCC servers in the same network node. This list allows any CEP to route requests for existing viewing sessions to the correct PCC server that created the session originally, as well as load balance new viewing session requests across all servers.

The list of servers is set by a HTTP PUT request to each Cloud Entry Point. Below is an example of the request that would be sent to each Cloud Entry Point (given the sample architecture shown in the diagram above):

PUT http://192.168.0.1:18682/PCCIS/V1/Service/Properties/Servers
{
    "servers": [
        {
            "address": "192.168.0.1",
            "port": "18681"
        },
        {
            "address": "192.168.0.2",
            "port": "18681"
        },
        {
            "address": "192.168.0.3",
            "port": "18681"
        }
    ]
}

This request would be repeated for the remaining two PCC servers, the only change being the port specified in the HTTP request.

Scaling

When PCC servers are added or removed from the node, it is important that the list of servers held by each Cloud Entry Point is updated to reflect the servers that are actually active. Otherwise, requests will begin failing when a server being routed to does not exist, and new servers will not receive their fair share of new viewing session requests because not every PCC server in the node is aware of them.

Keeping the server lists updated is a matter of repeating the requests described in the Start-up section above, only with updated JSON data that includes the new list of active servers.

Optimizing

Caching converted content plays a large role in the performance of the PCC HTTP service. In single server mode, caching is the most optimized because all converted content is available to the PCC service on that server. As requests for new viewing sessions are received, the new documents are examined to locate existing content that may already be created if the same document was used in a previous viewing session.

In multi-server mode, the PCC service on each server maintains its own cache data, separate from other PCC servers. Cache data is not shared across servers. Because of this, the effort to convert the same document will likely be duplicated on multiple PCC servers if you have a situation where users are frequently viewing the same document more than once.

To counteract this side-effect of multi-server mode, the PCC HTTP service provides a way to increase the chances that a request for a new viewing session will be sent to the same PCC server. This is done by providing a "hint" value in a HTTP header of the request to create new viewing sessions. Below is an example request that sets this header:

POST http://192.168.0.1:18682/PCCIS/V1/ViewingSession
Accusoft-Affinity-Hint: my-unique-document-name.docx
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "render": {
        "flash": {
            "optimizationLevel": 1
        },
        "html5": {
            "alwaysUseRaster": false
        }
    }
}

The Accusoft-Affinity-Hint header need only be specified in the HTTP request that creates a new viewing session.

It is important to note that the value used in this header should uniquely identify the document. A document name or a unique ID from a database are good options. Using the same value for documents that are not identical will unbalance the requests across the PCC servers as it will cause a single server to be favored for all requests that contain the same hint value.

©2014. Accusoft Corporation. All Rights Reserved.